---
title: Contributing to documentation
sidebarTitle: Documentation
---

Accessible documentation is a vital part of LangChain. We welcome both new documentation for new features/integrations, as well as community improvements to existing docs.

<Note>
    We generally do not merge new tutorials from outside contributors without an acute need.
</Note>

All documentation falls under one of four categories:

<CardGroup cols={2}>
    <Card title="Conceptual guides" icon="lightbulb" href="#conceptual-guides">
        Explanations that provide deeper understanding and insights
    </Card>

    <Card title="References" icon="book" href="#references">
        Technical descriptions of APIs and implementation details
    </Card>

    <Card title="Tutorials" icon="graduation-cap">
        Lessons that guide users through practical activities to build understanding
    </Card>

    <Card title="How-to guides" icon="wrench">
        Task-oriented instructions for users who know what they want to accomplish
    </Card>
</CardGroup>

---

## Getting started

### <Icon icon="text-slash" size={24}/> Quick edit: fix a typo

For simple changes like fixing typos, you can edit directly on GitHub without setting up a local development environment:

<Info>
    **Prerequisites:**
    - A GitHub account
    - Basic familiarity with GitHub's web interface for pull requests
</Info>

<Steps>
    <Step title="Find the page">
        Navigate to any documentation page and click the "suggest edits" link at the bottom
    </Step>

    <Step title="Fork the repository">
        GitHub will prompt you to fork the repository to your account. Make sure to fork into your <Tooltip tip="If you clone to an organization, maintainers are unable to make edits.">personal account</Tooltip>!
    </Step>

    <Step title="Make your changes">
        Correct the typo directly in GitHub's web editor
    </Step>

    <Step title="Commit your changes">
        Click `Commit changes...` and give your commit a descriptive title like `fix(docs): description`
    </Step>

    <Step title="Create pull request">
        GitHub will redirect you to create a pull request. Title it like `docs: Fix typo in X` and follow the PR template checklist
    </Step>
</Steps>

<Note>
    Docs PRs are typically reviewed within a few days. Keep an eye on your PR to address any feedback from maintainers.
</Note>

### Full development IDE setup

For larger changes or ongoing contributions, set up a local development environment. Our documentation is built using [Mintlify](https://mintlify.com/), which offers local preview and live reload as you edit.

<Steps>
    <Step title="Local repo">
        :::python
        Clone our [documentation repository](https://github.com/langchain-ai/docs) unless you plan to update API references only, in which case you can fork the relevant repo (e.g. [`langchain`](https://github.com/langchain-ai/langchain) or [`langgraph`](https://github.com/langchain-ai/langgraph))
        :::
        :::js
        Clone our [documentation repository](https://github.com/langchain-ai/docs) unless you plan to update API references only, in which case you can fork the relevant repo (e.g. [`langchainjs`](https://github.com/langchain-ai/langchainjs) or [`langgraphjs`](https://github.com/langchain-ai/langgraphjs)).
        :::
    </Step>

    <Step title="Mintlify knowledge">
        Review the [Mintlify documentation](https://mintlify.com/docs) for component usage and best practices - you can also refer to existing docs for examples
    </Step>

    <Step title="Build system & development environment">
        Set up your development environment following our the steps below
    </Step>

</Steps>

This repository includes configuration files to ensure consistent formatting across different editors:

<Tabs>
    <Tab title="VSCode">
        Settings in `.vscode/settings.json` are automatically applied when you open the project. No additional setup required.

        **Recommended extensions:**
        - [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)
        - [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)
        - [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx)

        When you open the "Extensions" tab in VSCode, it may prompt you to install these extensions automatically.
    </Tab>

    <Tab title="Other IDEs">
        Most modern IDEs support [EditorConfig](https://editorconfig.org/). The `.editorconfig` file automatically configures:
        - IntelliJ IDEA / PyCharm / WebStorm
        - Sublime Text / Atom
        - Vim / Emacs

        Install the EditorConfig plugin if needed and restart your IDE.
    </Tab>
</Tabs>

### Build system

<Warning>
    Only edit files in `src/` - The `build/` directory is automatically generated!
</Warning>

Our documentation uses a build pipeline that allows us to write in MDX and use Mintlify components. The source files are in `src/` and the built output is in `build/`. You are able to run a local development server with hot reload to see changes in your browser immediately.

<Steps>
    <Step title="Install dependencies">
        You will need to install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) and [`mint`](https://mintlify.com/docs/installation) if you haven't already. Also, be sure to [clone the docs](#full-development-setup) repository

        ```bash
        cd docs
        uv venv
        source .venv/bin/activate
        uv sync --all-groups
        npm i -g mint
        ```
    </Step>

    <Step title="Start development server">
        Run from the project root:

        ```bash
        docs dev
        ```

        This starts a development server with hot reload at http://localhost:3000 (unless overridden).
    </Step>

    <Step title="Make your changes">
        Edit files in `src/` and see changes reflected immediately in your browser
    </Step>
</Steps>

---

## <Icon icon="book" size={24}/> Documentation types

<Note>
    Where applicable, all documentation must have translations in both Python and JavaScript/TypeScript. See [our localization guide](#localization) for details.
</Note>

### Conceptual guides

Conceptual guide cover core concepts abstractly, providing deep understanding.

<AccordionGroup>
    <Accordion title="Characteristics">
        - **Understanding-focused**: Explain why things work as they do
        - **Broad perspective**: Higher and wider view than other types
        - **Design-oriented**: Explain decisions and trade-offs
        - **Context-rich**: Use analogies and comparisons
    </Accordion>

    <Accordion title="Tips">
        - Explain design decisions - *why does concept X exist?*
        - Use analogies and reference alternatives
        - Avoid blending in too much reference content
        - Link to related tutorials and how-to guides
        - Focus on the **"why"** rather than the "how"
    </Accordion>
</AccordionGroup>

**Example pages**
- [Memory](/oss/concepts/memory)
- [Context](/oss/concepts/context)
- [Subgraphs](/oss/concepts/subgraphs)

### References

References contain detailed, low-level information describing exactly what functionality exists and how to use it.

<AccordionGroup>
    <Accordion title="Reference characteristics">
        - **Information-focused**: Describe what exists
        - **Comprehensive**: Cover all parameters and options
        - **Structured**: Organized systematically
        - **Authoritative**: The definitive source for technical details
    </Accordion>

    <Accordion title="Types of LangChain references">
        - **API references**: Auto-generated from code docstrings
        - **Integration guides**: Manual documentation for specific providers/tools
        - **Configuration references**: Detailed parameter specifications
        - **Schema documentation**: Data structure and format specifications
    </Accordion>

    <Accordion title="Contributing to references">
        - **API references**: Update docstrings in source code repositories
        - **Integration guides**: Create/edit `.mdx` files in the [docs repository](https://github.com/langchain-ai/docs) under `/src/`
        - **Manual references**: Edit existing pages
    </Accordion>

    <Accordion title="LangChain reference best practices">
        - **Integration consistency**: Follow existing patterns for provider-specific documentation
        - **Code examples**: Include both basic usage and common edge cases/failure modes
        - **Version compatibility**: Note when features require specific versions
    </Accordion>
</AccordionGroup>

**Existing references**
- [LangChain Python API reference](https://python.langchain.com/api_reference/) (auto-generated from docstrings)
- [LangChain JavaScript/TypeScript API reference](https://v03.api.js.langchain.com/index.html) (auto-generated from docstrings)

**When to create new reference documentation:**
- New integrations or providers need dedicated reference pages
- Complex configuration options require detailed explanation
- API changes introduce new parameters or behavior
- Community frequently asks questions about specific functionality

---

## <Icon icon="pen" size={24}/> Writing standard

### Mintlify components

Use appropriate [Mintlify components](https://mintlify.com/docs/text) to enhance readability:

<Tabs>
    <Tab title="Callouts">
    - `<Note>` for helpful supplementary information
    - `<Warning>` for important cautions and breaking changes
    - `<Tip>` for best practices and advice
    - `<Info>` for neutral contextual information
    - `<Check>` for success confirmations
</Tab>

<Tab title="Structure">
    - `<Steps>` for sequential procedures
    - `<Tabs>` for platform-specific content
    - `<AccordionGroup>` and `<Accordion>` for progressive disclosure
    - `<CardGroup>` and `<Card>` for highlighting content
</Tab>

<Tab title="Code">
    - `<CodeGroup>` for multiple language examples
    - Always specify language tags on code blocks
    - Titles for code blocks (e.g. `Success`, `Error Response`)
    </Tab>
</Tabs>

### Page structure

Every documentation page must begin with YAML frontmatter:

```yaml
---
title: "Clear, specific title"
---
```

### Localization

All documentation must be localized in both Python and JavaScript/TypeScript when possible. To do so, we use a custom in-line syntax to differentiate between sections that should appear in one or both languages:

```mdx
\:::python
Python-specific content. In real docs, the preceding backslash (before `python`) is omitted.
\:::

\:::js
JavaScript/TypeScript-specific content. In real docs, the preceding backslash (before `js`) is omitted.
\:::

Content for both languages (not wrapped)
```

<Note>
    We don't want a lack of parity to block contributions. If a feature is only available in one language, it's okay to have documentation only in that language until the other language catches up. In such cases, please include a note indicating that the feature is not yet available in the other language.
</Note>
<Note>
    If you need help translating content between Python and JavaScript/TypeScript, please ask in the [community slack](https://www.langchain.com/join-community) or tag a maintainer in your PR.
</Note>

---

## <Icon icon="star" size={24}/> Quality standards

### General guidelines

<AccordionGroup>
    <Accordion title="Avoid duplication">
        Multiple pages covering the same material are difficult to maintain and cause confusion. There should be only one canonical page for each concept or feature. Link to other guides instead of re-explaining.
    </Accordion>

    <Accordion title="Link frequently">
        Documentation sections don't exist in a vacuum. Link to other sections frequently to allow users to learn about unfamiliar topics. This includes linking to API references and conceptual sections.
    </Accordion>

    <Accordion title="Be concise">
        Take a less-is-more approach. If another section with a good explanation exists, link to it rather than re-explain, unless your content presents a new angle.
    </Accordion>
</AccordionGroup>

### Accessibility requirements

Ensure documentation is accessible to all users:

- Structure content for easy scanning with headers and lists
- Use specific, actionable link text instead of "click here"
- Include descriptive alt text for all images and diagrams

### Testing and validation

Before submitting documentation:

<Steps>
    <Step title="Test all code">
        Run all code examples to ensure they work correctly
    </Step>

    <Step title="Check formatting">
        ```bash
        make lint
        make format
        ```
    </Step>

    <Step title="Build locally">
        ```bash
        docs build
        ```
        Verify the build completes without errors
    </Step>

    <Step title="Review links">
        Check that all internal links work correctly
    </Step>
</Steps>

---

## <Icon icon="i-cursor" size={24}/> In-code documentation

### Language and style

<Info>
    Use [Google-style docstrings](https://google.github.io/styleguide/pyguide.html) with complete type hints for all public functions.
</Info>

Follow these standards for all documentation:

- **Voice**: Use second person ("you") for instructions
- **Tense**: Use active voice and present tense
- **Clarity**: Write clear, direct language for technical audiences
- **Consistency**: Use consistent terminology throughout
- **Conciseness**: Keep sentences concise while providing necessary context

### Code examples

<Warning>
    Always test code examples before publishing. Never include real API keys or secrets.
</Warning>

Requirements for code examples:

<Steps>
    <Step title="Completeness">
        Include complete, runnable examples that users can copy and execute without errors
    </Step>

    <Step title="Realism">
        Use realistic data instead of placeholder values like "foo" or "example"
    </Step>

    <Step title="Error handling">
        Show proper error handling and edge case management
    </Step>

    <Step title="Documentation">
        Add explanatory comments for complex logic
    </Step>
</Steps>

Example of a well-documented function:

```python
def filter_unknown_users(users: list[str], known_users: set[str]) -> list[str]:
    """Filter out users that are not in the known users set.

    Args:
        users: List of user identifiers to filter.
        known_users: Set of known/valid user identifiers.

    Returns:
        List of users that are not in the known_users set.

    Raises:
        ValueError: If users list contains invalid identifiers.
    """
    return [user for user in users if user not in known_users]
```

## Getting help

Our goal is to have the simplest developer setup possible. Should you experience any difficulty getting setup, please ask in the [community slack](https://www.langchain.com/join-community) or open a [forum post](https://forum.langchain.com/).

<Check>
    You now have everything you need to contribute high-quality documentation to LangChain!
</Check>
